<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<HEAD>

<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<link REL="STYLESHEET" HREF="../../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
   <title>Eclipse Platform - Naming Conventions</title>
</head>
<body>
<h1>
Eclipse Platform<br>
Naming Conventions</h1>
<i>Last revised August 15, 2012</i>
<p>Naming conventions and guidelines for the Eclipse Platform:</p>
<ul>
<li>
<a href="#Java Packages">Java packages</a></li>

<li>
<a href="#Classes and Interfaces">Classes and interfaces</a></li>

<li>
<a href="#Methods">Methods</a></li>

<li>
<a href="#Variables">Variables</a></li>

<li>
<a href="#Plug-ins">Plug-ins and extension points</a></li>
</ul>

<h2>
<a NAME="Java Packages"></a><b>Java Packages</b></h2>
The Eclipse Platform consists of a collection of Java packages. The package
namespace is managed in conformance with <a href="http://www.oracle.com/technetwork/java/codeconventions-135099.html#367">Java's
package naming guidelines</a>; subpackages should not be created without
prior approval from the owner of the package sub-tree. The packages for
the Eclipse platform are all subpackages <b><tt>org.eclipse</tt></b>. The
first package name component after <b><tt>org.eclipse</tt></b> is called
the <i>major </i>package name. The following major packages of <b><tt>org.eclipse</tt></b>
are assigned in the Eclipse 4.3 release:
<blockquote><b><tt>org.eclipse.ant[.*]</tt> </b>- Ant support
<br><b><tt>org.eclipse.compare[.*]</tt></b> - Compare support
<br><b><tt>org.eclipse.core[.*]</tt> </b>- Platform core
<br><b><tt>org.eclipse.debug[.*]</tt> </b>- Debug
<br><b><tt>org.eclipse.equinox[.*]</tt> </b>- Equinox sub-project
<br><b><tt>org.eclipse.help[.*]</tt></b> - Help support
<br><b><tt>org.eclipse.jdi[.*]</tt> </b>- Eclipse implementation of Java
Debug Interface (JDI)
<br><b><tt>org.eclipse.jdt[.*]</tt> </b>- Java development tools
<br><b><tt>org.eclipse.jface[.*]</tt> </b>- JFace
<br><b><tt>org.eclipse.jsch[.*]</tt> </b>- Jsch SSH library support
<br><b><tt>org.eclipse.ltk[.*]</tt> </b>- Generic language tool infrastructure
<br><b><tt>org.eclipse.osgi[.*]</tt> </b>- Eclipse API for interacting with OSGi
<br><b><tt>org.eclipse.pde[.*]</tt></b> - Plug-in Development Environment
<br><b><tt>org.eclipse.search[.*]</tt></b> - Search support
<br><b><tt>org.eclipse.swt[.*]</tt> </b>- Standard Widget Toolkit
<br><b><tt>org.eclipse.team[.*]</tt> </b>- Team support and Version and
  Configuration Management
<br><b><tt>org.eclipse.text[.*]</tt> </b>- Text editor framework
<br><b><tt>org.eclipse.ui[.*]</tt></b> - Workbench
<br><b><tt>org.eclipse.update[.*]</tt></b> - Update/install
</blockquote>
The following package name segments are reserved:
<blockquote><b><tt>internal</tt></b> - indicates an internal implementation
package that contains no API
<br><b><tt>tests</tt></b> - indicates a non-API package that contains only
test suites
<br><b><tt>examples</tt></b> - indicates a non-API package that contains
only examples</blockquote>
These name are used as qualifiers, and must only appear following the major
package name. For example,
<blockquote><b><tt>org.eclipse.core.internal.resources</tt></b> - Correct
usage
<br><b><tt>org.eclipse.internal.core.resources</tt></b> - Incorrect. <b><tt>internal</tt></b>
precedes major package name.
<br><b><tt>org.eclipse.core.resources.internal</tt></b> - Incorrect. <b><tt>internal</tt></b>
does not immediately follow major package name.</blockquote>
<p>
Aside on how the Eclipse Platform is structured: The Eclipse Platform is
divided up into <i>Core </i>and <i>UI</i>. Anything classified as Core
is independent of the window system; applications and plug-ins that depend
on the Core and not on the UI can run headless. The distinction between
Core and UI does not align with the distinction between API and non-API;
both Core and UI contain API. The UI portion of the Eclipse Platform is
known as the Workbench. The Workbench is a high-level UI framework for
building products with sophisticated UIs built from pluggable components.
The Workbench is built atop JFace, SWT, and the Platform Core. SWT (Standard
Widget Toolkit) is a low-level, OS-platform-independent means of talking
to the native window system. JFace is a mid-level UI framework useful for
building complex UI pieces such as property viewers. SWT and JFace are
UI by definition. The Java tooling is a Java IDE built atop the workbench.
End aside.</p>
<p><b>API Packages</b>&nbsp; API packages are ones that contain classes
and interfaces that must be made available to ISVs. The names of API packages
need to make sense to the ISV. The number of different packages that the
ISV needs to remember should be small, since a profusion of API packages
can make it difficult for ISVs to know which packages they need to import.
Within an API package, all public classes and interfaces are considered
API. The names of API packages should not contain <b><tt>internal</tt></b>,
<b><tt>tests</tt></b>,
or <b><tt>examples</tt></b> to avoid confusion with the scheme for naming
non-API packages.</p>
<p><b>Internal Implementation Packages</b>&nbsp; All packages that are
part of the platform implementation but contain no API that should be exposed
to ISVs are considered internal implementation packages. All implementation
packages should be flagged as <b><tt>internal</tt></b>, with the tag occurring
just after the major package name. ISVs will be told that all packages
marked <b><tt>internal</tt></b> are out of bounds. (A simple text search
for "<tt>.internal.</tt>" detects suspicious reference in source files;
likewise, "/<tt>internal/</tt>" is suspicious in .class files).</p>
<p><b>Test Suite Packages</b>&nbsp; All packages containing test suites
should be flagged as <b><tt>tests</tt></b>, with the tag occurring just
after the major package name. Fully automated tests are the norm; so, for
example,
<tt>org.eclipse.core.tests.resources</tt> would contain automated
tests for API in <tt>org.eclipse.core.resources</tt>. Interactive tests
(ones requiring a hands-on tester) should be flagged with <b><tt>interactive</tt></b>
as the <i>last</i> package name segment; so, for example, <tt>org.eclipse.core.tests.resources.interactive</tt>
would contain the corresponding interactive tests.</p>
<p><b>Examples Packages</b>&nbsp; All packages containing examples that
ship to ISVs should be flagged as <b><tt>examples</tt></b>, with the tag
occurring just after the major package name. For example,
<tt>org.eclipse.swt.examples</tt>
would contain examples for how to use the SWT API.</p>
<p>Additional rules:</p>
<ul>
<li>
Package names should contain only lowercase ASCII alphanumerics, and avoid
underscore <tt>_</tt> or dollar sign <tt>$</tt> characters.</li>
</ul>

<h2>
<a NAME="Classes and Interfaces"></a><b>Classes and Interfaces</b></h2>
<p><a href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html">Java's naming guidelines</a>
state</p>
<blockquote>Class names should be nouns, in mixed case with the first letter
of each internal word capitalized. Try to keep your class names simple
and descriptive. Use whole words - avoid acronyms and abbreviations (unless
the abbreviation is much more widely used than the long form, such as URL
or HTML).<br>&nbsp;
<br>Examples:
<br><tt>&nbsp;&nbsp;&nbsp; class Raster;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; class ImageSprite;</tt> <br>&nbsp;
<br>Interface names should be capitalized like class names.</blockquote>
<p>For interface names, we follow the "I"-for-interface convention: all interface
names are prefixed with an "<tt>I</tt>". For example, "<tt>IWorkspace</tt>"
or "<tt>IIndex</tt>". This convention aids code readability by making interface
names more readily recognizable. (Microsoft COM interfaces subscribe to
this convention).</p>
<p>Additional rules:</p>
<ul>
<li>
The names of exception classes (subclasses of <tt>Exception</tt>) should
follow the common practice of ending in "<tt>Exception</tt>".</li>
</ul>

<h2>
<a NAME="Methods"></a><b>Methods</b></h2>
<p><a href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html">Java's naming guidelines</a>
state</p>
<blockquote>Methods should be verbs, in mixed case with the first letter
lowercase, with the first letter of each internal word capitalized.<br>&nbsp;
<br>Examples:
<br><tt>&nbsp;&nbsp;&nbsp; run();</tt>
<br><tt>&nbsp;&nbsp;&nbsp; runFast();</tt>
<br><tt>&nbsp;&nbsp;&nbsp; getBackground();</tt></blockquote>
Additional rules:
<ul>
<li>
The named of methods should follow common practice for naming getters (<tt>get<i>X</i>()</tt>),
setters (<tt>set<i>X</i>()</tt>), and predicates (<tt>is<i>X</i>()</tt>,
<tt>has<i>X</i>()</tt>).</li>
</ul>

<h2>
<a NAME="Variables"></a><b>Variables</b></h2>
<p><a href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html">Java's naming guidelines</a>
state</p>
<blockquote>Except for variables, all instance, class, and class constants
are in mixed case with a lowercase first letter. Internal words start with
capital letters. Variable names should not start with underscore <tt>_</tt>
or dollar sign <tt>$ </tt>characters, even though both are allowed.<br>&nbsp;
<br>Variable names should be short yet meaningful. The choice of a variable
name should be mnemonic - that is, designed to indicate to the casual observer
the intent of its use. One-character variable names should be avoided except
for temporary "throwaway" variables. Common names for temporary variables
are <tt>i</tt>, <tt>j</tt>, <tt>k</tt>, <tt>m</tt>, and <tt>n</tt> for
integers; <tt>c</tt>, <tt>d</tt>, and <tt>e</tt> for characters.<br>&nbsp;
<br>Examples:
<br><tt>&nbsp;&nbsp;&nbsp; int i;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; char c;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; float myWidth;</tt></blockquote>
<p>(Note: we are no longer following the convention that prefixes non-constant
field names with "<tt>f</tt>", such as "<tt>fWidget</tt>".)</p>
<h2>
<a NAME="Constants"></a><b>Constants</b></h2>
<p><a href="http://www.oracle.com/technetwork/java/codeconvtoc-136057.html">Java's naming guidelines</a>
states</p>
<blockquote>The names of variables declared class constants and of ANSI
constants should be all uppercase with words separated by underscores (&quot;_&quot;).<br>&nbsp;
<br>Examples:
<br><tt>&nbsp;&nbsp;&nbsp; static final int MIN_WIDTH = 4;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; static final int MAX_WIDTH = 999;</tt>
<br><tt>&nbsp;&nbsp;&nbsp; static final int GET_THE_CPU = 1;</tt></blockquote>

<h2>
<a NAME="Plug-ins"></a><b>Plug-ins and Extension Points</b></h2>
<p>All plug-ins, including the ones that are part of the Eclipse Platform,
like the Resources and Workbench plug-ins, must have unique identifiers
following the same naming pattern as Java packages. For example, workbench
plug-ins are named <b><tt>org.eclipse.ui[.*]</tt></b>.</p>
<p>The plug-in namespace is managed hierarchically; do not create plug-in
without prior approval from the owner of the enclosing namespace.</p>
<p>Extension points that expect multiple extensions should have plural
names. For example, "<tt>builders</tt>" rather than "<tt>builder</tt>".
</p>
</body>
</html>
